13장 여러 작업 동시에 시키기 (입문판)

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호)

이 장에서 딱 6가지만 기억하세요. 1. 서브에이전트는 클로드 코드가 일을 떼어주는 "팀원"이에요. 2. 독립적인 일은 여러 팀원에게 한꺼번에 시켜요 (병렬 실행). 3. 줄줄이 이어지는 일은 한 명씩 차례로 시켜요 (직렬 실행). 4. 자주 쓰는 팀원은 /agent 로 미리 "전문가"로 등록해둬요 (커스텀 서브에이전트). 5. 등록한 전문가에게 "이건 하지 마"라고 못박아 사고를 막아요. 6. 진짜 따로 떨어진 창에서 동시에 일하려면 Git Worktree 로 작업 폴더를 나눠요.

이 장은 클로드 코드에게 일을 "한 번에 하나씩"이 아니라 "여러 개를 동시에" 시키는 방법을 배웁니다. 요금제, 모델 이름, 콘텍스트 한도 같은 숫자는 빠르게 바뀌어요. 이 노트의 구체적인 숫자(예: 200K 토큰)는 원서/노트 기준 예시이며, 최신 값은 공식 문서(클로드 코드 공식 문서)에서 확인하세요.

0. 시작하기 전에 — 이런 적 있죠?

혼자서 큰 일을 다 떠안아 본 적 있나요?

이사 가는 날을 떠올려 보세요. 짐 싸기, 청소, 전입신고, 인터넷 옮기기를 혼자 순서대로 하면 하루가 다 가요. 그런데 친구 셋이 와서 한 명은 짐 싸고, 한 명은 청소하고, 한 명은 전입신고를 맡으면? 같은 일이 훨씬 빨리 끝나죠.

클로드 코드도 똑같아요. 원래는 일을 하나씩 처리하지만, "팀원"을 불러 동시에 시킬 수 있어요. 이 팀원이 바로 이 장의 주인공, 서브에이전트예요.

이 장에서 새로 나오는 말 몇 개를 미리 한 줄씩 풀어둘게요. (어려운 말은 0장 용어집에도 있다고 생각하고, 처음 나올 때 짧게 뜻을 붙여요.)

• 콘텍스트: AI가 지금 대화에서 "기억하고 참고하는 전체 내용". 책상 위에 펼쳐둔 자료 전부라고 보면 돼요.
• 토큰: AI가 글을 세는 단위. 한국어 한 글자가 대략 토큰 2~3개예요. 글이 길수록 토큰이 많이 들어요.
• 200K 토큰: 클로드가 한 번에 펼쳐둘 수 있는 자료의 최대치(원서/노트 기준 예시). 책상이 무한히 넓진 않다는 뜻이에요.

앞 장에서 봤던 Todo 리스트(클로드가 할 일을 체크박스로 정리해 보여주는 것)도 이 장에서 다시 나와요. 서브에이전트가 여러 개 돌아갈 때, Todo 리스트로 누가 무슨 일을 하는지 한눈에 보입니다.

이 장의 기법들을 한 단어로 묶으면

이 장에서 배울 것들을 떠올려 보세요. 일을 팀원에게 떼어주고(서브에이전트), 여럿에게 동시에 시키고(병렬), 한 명씩 차례로 시키고(직렬), 전문가로 등록해두고(커스텀), 폴더를 나눠 따로 돌리는(워크트리) 것까지. 이 다섯 가지에는 공통점이 하나 있어요. 내가 일일이 손대지 않고, "일을 맡기면 알아서 단계를 밟아 끝내게 한다"는 점이에요.

회사로 비유하면, 내가 모든 일을 직접 하는 게 아니라 직원에게 맡기고 결과만 받는 것과 같아요. 이렇게 일을 맡겨 두는 방식 전체를 부르는 이름이 따로 있어요.

용어 한 줄: 이렇게 AI 에이전트에게 일을 맡겨 스스로 단계를 밟아 끝내게 하는 방식을 에이전틱 프로그래밍(Agentic Programming)이라고 불러요. (내가 한 줄씩 명령하는 대신, 똑똑한 직원에게 일을 통째로 맡기는 것과 같아요.)

이 말이 지금 당장 와닿지 않아도 괜찮아요. "이 장에서 배우는 게 다 한 가족이고, 그 가족 이름이 에이전틱 프로그래밍이구나" 정도만 기억하면 충분해요.

1. 서브에이전트 — 일을 떼어주는 팀원

이렇게 막힌 적 있죠

클로드 코드에게 "테스트를 다 돌리고 부족한 테스트도 더 채워줘"처럼 큰 일을 시키면, 화면이 한참 동안 글자로 가득 차요. 그 긴 출력이 전부 클로드의 "책상"(콘텍스트)에 쌓이면, 정작 중요한 대화 내용은 밀려나서 클로드가 헷갈리기 시작해요.

그게 바로 서브에이전트가 필요한 순간이에요.

그게 바로 서브에이전트예요

서브에이전트는 클로드 코드(메인에이전트)가 일을 떼어주려고 부르는 "팀원"이에요. 한 문장 뜻: 메인이 시킨 일만 따로 처리하고, 결과 요약만 돌려주는 별도의 작은 클로드.

팀장과 팀원으로 비유하면 이래요.

• 팀장(메인에이전트): 전체 그림을 보고, 일을 나눠 맡기고, 결과 보고만 받아요.
• 팀원(서브에이전트): 시킨 일만 혼자 해요. 지난 회의 내용은 몰라요. 끝나면 결과만 보고해요.

핵심은 이거예요. 팀원이 100페이지짜리 보고서를 썼어도, 팀장은 3줄 요약만 받으니 머리가 안 복잡해요.

직접 눈으로 보기

클로드 코드에게 큰 일을 시키면, 클로드가 알아서 팀원을 부르기도 해요.

예를 들어 이렇게 시켜봐요.

테스트를 실행하고 커버리지를 개선해줘

그러면 화면에 이런 게 떠요.

● Task(테스트 실행 및 커버리지 개선)
  └ Initializing...

여기서 Task 라고 뜨면서 Initializing 이 보이면, 팀원(서브에이전트)이 만들어지는 중이에요. 일이 끝나면 이렇게 바뀝니다.

● Task(테스트 실행 및 커버리지 개선)
  └ Done (70 tool uses · 127.6k tokens · 12m 19.6s)

이 줄을 잘 보세요. 팀원은 127.6K 토큰이나 썼어요. 그런데 팀장(메인)은 그중 215 토큰만 받았어요. 즉, 127K 가까운 분량을 메인의 책상에서 아낀 거예요.

잘못된 생각 vs 올바른 생각

• 잘못된 생각: "서브에이전트가 토큰을 많이 썼으니 내 콘텍스트도 다 닳았겠지."
• 올바른 생각: "팀원이 많이 썼어도, 메인은 요약만 받아서 거의 안 닳았어."

한 걸음 더 ▸ 누가 팀원을 부르나

팀원을 부르는 방법은 두 가지예요.

• 클로드가 알아서 부름: 일이 크면 자동으로 Task 를 띄워요.
• 내가 시켜서 부름: 프롬프트에 "subagent 로 처리해줘"라고 콕 집어 말하면 돼요.

지금은 "자동으로도 되고, 내가 시킬 수도 있다" 정도만 알면 충분해요.

2. 병렬 실행 — 여러 팀원에게 한꺼번에

이렇게 막힌 적 있죠

웹사이트를 영어, 일본어, 중국어, 아랍어 네 나라 말로 번역해야 해요. 한 명이 영어 다 하고, 그다음 일본어, 그다음 중국어... 이렇게 하면 시간이 네 배로 들어요. 근데 이 네 가지 번역은 서로 상관이 없잖아요? 영어 번역이 일본어 번역에 영향을 주지 않아요.

그럴 때 쓰는 게 병렬 실행이에요.

그게 바로 병렬 실행이에요

병렬 실행은 서로 상관없는 일들을 여러 팀원에게 동시에 맡기는 방식이에요. 한 문장 뜻: 독립적인 작업을 서브에이전트 여러 개로 한꺼번에 처리하는 것.

식당 주방으로 비유해 볼게요.

요리사 한 명이 다 하면:

스프(10분) → 스테이크(15분) → 디저트(10분) = 총 35분

요리사 세 명이 동시에 하면:

요리사A: 스프(10분)
요리사B: 스테이크(15분)   ← 셋이 동시에
요리사C: 디저트(10분)
= 가장 오래 걸리는 15분이면 끝!

실제로 시켜보기

번역을 네 개로 나눠 동시에 시키는 프롬프트 예예요.

# 역할
너는 지금부터 다국어 번역 전문가야.
홈페이지를 영어, 일본어, 중국어, 아랍어로 번역하는 걸 도와줘.

# 작업 순서
- 번역할 텍스트를 전부 찾아줘
- 영어, 일본어, 중국어, 아랍어로 번역해줘
- 각 언어별로 subagent 4개를 동시에 생성해서 parallel 로 작업해줘
- 번역 외에 다른 작업은 하지 말아줘
- 끝나면 테스트, 린트, 빌드를 실행하고 에러가 없는지 확인해줘

여기서 핵심은 "subagent 4개를 동시에 생성해서 parallel 로"라는 한 줄이에요. 이렇게 말하면 클로드가 팀원 넷을 한꺼번에 부려요.

실행하면 Todo 리스트가 이렇게 떠요.

● Update Todos
  □ 홈페이지에서 번역할 텍스트 찾기
  □ 영어로 번역 (subagent)
  □ 일본어로 번역 (subagent)
  □ 중국어로 번역 (subagent)
  □ 아랍어로 번역 (subagent)
  □ 테스트, 린트, 빌드 실행 및 에러 확인

네 줄(영어/일본어/중국어/아랍어)이 동시에 돌아가는 거예요.

병렬이 좋은 일 vs 나쁜 일

병렬로 하면 좋은 일이에요.

• 여러 나라 말로 동시에 번역
• 많은 테스트를 여러 덩어리로 나눠 동시에 실행
• 여러 디자인 시안을 동시에 만들기
• 깃허브 이슈 여러 개를 동시에 생성

병렬로 하면 안 되는 일이에요.

• 작업 B가 작업 A의 결과를 받아야 하는 경우
• 같은 파일을 여러 팀원이 동시에 고치는 경우
• 순서가 중요한 데이터 처리 (한 단계씩 흘러가야 하는 작업)

잘못된 예 vs 올바른 예

• 잘못된 예: "스키마 만들고, 그 스키마로 API도 같이 동시에 만들어줘." → API 는 스키마가 있어야 만들 수 있어요. 동시에 시키면 팀원이 헤매요.
• 올바른 예: "서로 상관없는 영어/일본어/중국어 번역을 subagent 로 동시에 해줘." → 셋이 따로 놀아도 되니 동시에 시켜도 안전해요.

이럴 때 이렇게: 일을 나눌 때 "이 둘이 서로를 기다려야 하나?"를 먼저 물어보세요. 기다릴 일 없으면 병렬, 기다려야 하면 다음 절의 직렬이에요.

기억할 점

• 병렬은 독립적인 일을 동시에 할 때 빨라요.
• 일끼리 충돌하면 아무리 많이 띄워도 오히려 느려져요.
• 프롬프트에 "subagent 로 parallel 작업해줘"라고 적어요.
• 토큰은 팀원 수만큼 더 들지만, 아낀 시간 가치가 훨씬 커요.

3. 직렬 실행 — 한 명씩 차례로

이렇게 막힌 적 있죠

만들 게 너무 많아요. 회원 정보를 만들고(Create), 읽고(Read), 고치고(Update), 지우는(Delete) 기능 네 개를 한 명에게 다 시켰더니, 출력이 어마어마하게 쏟아져서 클로드의 책상(콘텍스트)이 꽉 차버렸어요. 200K 토큰을 훌쩍 넘겨서 앞 내용을 까먹기 시작해요.

이럴 땐 한꺼번에 말고, 한 명씩 차례로 시키는 게 나아요. 그게 직렬 실행이에요.

그게 바로 직렬 실행이에요

직렬 실행은 팀원을 하나씩 차례로 불러, 일을 순서대로 처리하는 방식이에요. 한 문장 뜻: 서브에이전트를 한 번에 하나씩 생성해 콘텍스트 200K 한도를 아껴 쓰는 방법. (CRUD 는 Create·Read·Update·Delete, 즉 데이터를 만들고·읽고·고치고·지우는 네 가지 기본 기능이에요.)

릴레이 달리기로 비유해 볼게요.

감독(메인에이전트)        주자(서브에이전트)

감독: "1번 주자, 1구간 뛰어!"
1번 주자: (뛰고) → 결과 보고
감독: "좋아. 2번 주자, 2구간!"
2번 주자: (뛰고) → 결과 보고
감독: "마지막. 3번 주자, 3구간!"
3번 주자: (뛰고) → 결과 보고

각 주자는 자기 구간만 뛰고, 감독은 바통(결과 요약)만 받아요. 그래서 감독의 체력(콘텍스트)은 거의 안 닳아요.

실제로 시켜보기

CRUD 네 개를 직렬로 나누면 흐름이 이래요.

메인에이전트 (워크플로 제어)
   → 서브에이전트1: Create 만들기 → 결과 요약 보고
   → 메인이 확인
   → 서브에이전트2: Read 만들기   → 결과 요약 보고
   → (Update, Delete 도 같은 식으로)

한 명에게 CRUD 를 다 시키면 컨트롤러·서비스·리포지터리를 전부 다뤄야 해서 너무 복잡해져요. 나눠 시키면 메인은 순서 관리만, 실제 작업은 팀원이 하나씩 맡아요.

테스트를 직렬로 시키는 프롬프트 예예요.

테스트를 subagent 에서 독립적으로 실행해줘.
subagent 에게 "pnpm run test 를 실행해서 테스트를 돌리고,
에러가 있으면 해결해줘. 커버리지가 80% 이상이 되도록
필요한 곳에 테스트를 더 작성해줘"라고 전달해줘

(pnpm 은 프로젝트마다 다른 테스트 실행 도구의 한 예예요. 여러분 프로젝트에 맞는 명령으로 바꾸면 돼요.)

직렬이 유리한 상황

• 200K 토큰을 넘길 만큼 큰 작업
• 한 명이 감당하기 벅찬 복잡한 코드
• 대규모 CRUD 엔드포인트 제작
• 테스트/린트/빌드 출력이 엄청 많을 때
• 메인의 콘텍스트를 최대한 아끼고 싶을 때

잘못된 예 vs 올바른 예

• 잘못된 예: "큰 CRUD 네 개를 한 번에 다 만들어줘." → 출력이 쏟아져 콘텍스트가 꽉 차고, 빌드/커밋까지 가기 전에 헤매요.
• 올바른 예: "Create 부터 subagent 하나로 끝내고, 결과 보고 다음 Read 를 시켜줘." → 한 명씩 끝내니 메인 책상은 늘 깔끔해요.

이럴 때 이렇게: 출력이 길 것 같은 일은 "한 명씩 차례로"가 기본이에요.

기억할 점

• 직렬은 실무에서 병렬보다 더 자주 쓰는 방법이에요.
• 200K 한도를 아끼는 핵심 전략이에요.
• 팀원이 결과만 돌려주니 콘텍스트 절약 효과가 커요.
• 사실 클로드 코드는 평소에도 이 방식을 내부에서 써요 (화면의 Task 가 그 흔적).

4. 커스텀 서브에이전트 — 자주 쓰는 팀원을 전문가로 등록

이렇게 막힌 적 있죠

테스트를 시킬 때마다 매번 똑같은 설명을 반복해요. "우리는 pnpm 으로 테스트하고, 커버리지는 80% 이상으로 맞춰줘." 매번 이걸 적으려니 귀찮고, 빠뜨리면 엉뚱하게 일해요.

이럴 때 팀원을 아예 "전문가"로 미리 등록해두면 돼요. 그게 커스텀 서브에이전트예요.

그게 바로 커스텀 서브에이전트예요

커스텀 서브에이전트는 자주 쓰는 역할을 미리 정의해둔 맞춤형 팀원이에요. 한 문장 뜻: /agent 명령이나 마크다운 파일로 역할을 미리 적어둔 전문 서브에이전트.

파견 직원과 전문 팀원으로 비유해 볼게요.

• 기본 서브에이전트 = 파견 직원: 올 때마다 "뭘 할까요?" 물어요. 회사 규칙을 매번 설명해야 해요.
• 커스텀 서브에이전트 = 전문 팀원: "테스트 전문가"로 정해져 있어 pnpm 도, 80% 기준도 이미 알아요. 설명 없이 바로 일해요.

만드는 순서 따라 하기

/agent 명령으로 화면을 따라가며 만들어요.

1단계: 명령 실행
  > /agent

2단계: 새 에이전트 선택
  > Create new agent

3단계: 저장 위치 선택
  1. Project  (.claude/agents/)    ← 이 프로젝트 전체에서 사용
  2. Personal (~/.claude/agents/)  ← 내 모든 프로젝트에서 사용

4단계: 만드는 방법 선택
  1. Generate with Claude (recommended)  ← 클로드가 자동으로 작성
  2. Manual configuration                ← 내가 직접 작성

5단계: 역할 설명 입력 (예시)
  "테스트가 실패하면 고치고, 커버리지를 80% 이상으로
   끌어올리는 에이전트를 만들어줘"

6단계: 사용할 도구 선택
  ☑ All tools         (모든 도구)
  ☑ Read-only tools   (읽기 전용)
  ☑ Edit tools        (편집)
  ☑ Execution tools   (실행)
  ☑ MCP & Other tools (MCP 등)

7단계: 색상 선택
  Red / Blue / Green / Yellow / Purple / Orange / Pink / Cyan

8단계: 확인 후 저장
  Name: test-coverage-optimizer
  Location: .claude/agents/test-coverage-optimizer.md
  Tools: All tools

(MCP 는 클로드 코드가 외부 도구와 연결되는 통로예요. 자세한 건 몰라도 이 장 실습엔 지장 없어요.)

다 끝나면 .claude/agents/ 폴더에 마크다운 파일 하나가 생겨요.

만들어진 파일은 어떻게 생겼나

파일을 열어보면 위쪽에 --- 사이로 메타데이터가 있어요. 이 --- 사이 영역을 프론트매터라고 불러요. 한 문장 뜻: 마크다운 파일 맨 위 --- 사이에 이름·설명·색 같은 정보를 적어두는 칸.

파일 위치: .claude/agents/test-coverage-optimizer.md

---
name: test-coverage-optimizer
description: Use this agent when you need to fix failing tests
  and improve test coverage to 80% or higher. ...
color: red
---

You are a Test Coverage Optimization Specialist...
(여기 아래에 이 팀원이 따를 역할 프롬프트가 이어짐)

프론트매터에 들어가는 세 가지예요.

여기서 가장 중요한 칸은 description 이에요. 클로드는 이 설명을 읽고 "아, 이 일은 이 팀원에게 시키자"라고 정하거든요.

등록한 전문가를 부르는 두 가지 방법

방법 1: 자동 부르기 (클로드가 description 보고 알아서 선택)
  "서브에이전트로 유닛 테스트를 실행하고 커버리지를 올려줘"
  → 클로드가 description 을 보고 test-coverage-optimizer 를 자동 선택

방법 2: 이름 콕 집기 (무조건 그 팀원 부르기)
  "test-coverage-optimizer 로 테스트를 실행하고 커버리지를 올려줘"
  → 이름을 직접 말해서 그 팀원을 강제로 실행

잘못된 예 vs 올바른 예

• 잘못된 예: description 을 "테스트 도와줌"처럼 너무 짧게 씀. → 클로드가 언제 부를지 헷갈려서 자동 선택이 잘 안 돼요.
• 올바른 예: "실패한 테스트를 고치고 커버리지를 80% 이상으로 올릴 때 사용"처럼 자세히 씀. → 클로드가 딱 맞는 순간에 알아서 불러요.

이럴 때 이렇게: 자동 트리거가 안 되면 description 을 더 자세히 쓰거나, 그냥 이름을 직접 말하세요.

한 걸음 더 ▸ 언어 이야기

자동 생성된 역할 프롬프트는 지금은 영어로 나와요. 그래도 만든 뒤에 그 파일을 한국어로 번역해서 바꿔도 잘 동작해요.

기억할 점

• /agent 로 만들고, .claude/agents/ 폴더에 마크다운 파일로 저장돼요.
• 프론트매터에 name, description, color 를 적어요.
• description 이 제일 중요해요 (클로드가 이걸 보고 팀원을 골라요).
• 저장 위치는 Project(이 프로젝트만) 또는 Personal(내 모든 프로젝트) 중 선택해요.

5. 커스텀 서브에이전트 활용 — 부서를 만들고 "하지 마"를 못박기

이렇게 막힌 적 있죠

데이터베이스를 다루는 팀원에게 "DB 좀 봐줘"라고 했더니, 글쎄, 멋대로 스키마(데이터를 담는 표의 구조)를 바꿔버렸어요. 보기만 시켰는데 손까지 댄 거죠. 이런 사고를 막으려면, 팀원에게 "이건 하지 마"를 미리 못박아둬야 해요.

전문 부서로 나눠 생각하기

커스텀 서브에이전트는 회사의 전문 부서처럼 만들 수 있어요.

CEO (메인에이전트)
   ├─ QA팀  : 테스트 전문
   ├─ UI팀  : 화면(Shadcn UI, Tanstack Table) 전문
   └─ DB팀  : 스키마는 절대 직접 안 건드림

각 부서는 자기 분야만 맡고, CEO(메인)는 조율만 해요. (Shadcn UI, Tanstack Table 은 화면을 만들 때 자주 쓰는 도구 모음의 한 예예요. 이름만 알아두면 돼요.)

활용 사례 세 가지

1. 테스트 에이전트
   - 테스트 실행, 실패 수정, 커버리지 80% 이상 달성
   - 메인의 콘텍스트를 안 쓰고, 통과/실패 결과만 보고

2. 아키텍처 레이어별 에이전트
   - 화면 만들 때: 늘 정해진 UI 라이브러리만 사용
   - 표 만들 때: 반드시 정해진 라이브러리 사용
   - 이 제약이 팀원이 일할 때마다 자동으로 들어감

3. "하면 안 되는 작업" 못박기
   잘못된 예: DB 팀원에게 스키마 변경을 허용
   올바른 예: "절대 스키마를 직접 만들지 말고,
              가이드라인만 마크다운 파일로 작성해"
   → 실수로 DB 를 망가뜨리는 사고를 막음

잘못된 예 vs 올바른 예

• 잘못된 예: "DB 검토해줘"만 적고 금지 규칙은 안 적음. → 팀원이 좋다고 스키마를 직접 고쳐버려요.
• 올바른 예: 역할 프롬프트에 "스키마 직접 수정 금지, 제안만 마크다운으로"라고 명시. → 검토는 하되 손은 안 대요.

이럴 때 이렇게: 위험한 작업이 있는 팀원일수록 "절대 ~ 하지 마"를 또렷이 적어두세요.

기억할 점

• 테스트 에이전트: 메인 콘텍스트 안 쓰고 결과만 받기.
• 레이어별 에이전트: UI/DB 같은 분야별 제약을 자동으로 주입.
• "하면 안 되는 작업" 명시로 위험한 실수를 막기.
• description 을 자세히 쓸수록 자동으로 부르는 정확도가 올라가요.

6. 독립 에이전트와 Git Worktree — 진짜 따로 떨어진 동시 작업

이렇게 막힌 적 있죠

터미널 창 두 개를 열고, 각각에서 클로드 코드를 켜서 동시에 일을 시켰어요. 한쪽은 프론트엔드, 한쪽은 백엔드. 그런데 둘 다 같은 프로젝트 폴더라서, 같은 파일을 동시에 고치다가 서로의 작업을 덮어써 버렸어요.

이 문제를 푸는 게 Git Worktree 예요.

서브에이전트 vs 독립 에이전트

먼저 이 둘을 구분해요.

• 서브에이전트: 한 사무실에서 팀장 지시를 받는 팀원 (메인이 관리).
• 독립 에이전트: 각자 다른 사무실에서 따로 일하는 개발자 (내가 직접 관리).

독립 에이전트는 터미널 창마다 클로드 코드를 따로 켜서 동시에 돌리는 방식이에요. 한 문장 뜻: 서브에이전트가 아니라, 완전히 별개로 실행되는 클로드 코드 인스턴스.

문제는 같은 폴더를 둘이 동시에 만지면 충돌난다는 거예요. 그래서 폴더 자체를 나눠줘야 하고, 그 도구가 Git Worktree 예요.

그게 바로 Git Worktree예요

Git Worktree 는 한 Git 저장소에서 작업 폴더를 여러 개 만드는 기능이에요. 한 문장 뜻: 같은 프로젝트를 여러 작업 폴더로 펼쳐, 각 폴더가 서로 다른 브랜치에서 따로 일하게 하는 것.

문서 비유로 정리하면 이래요.

프로젝트  = 원본 문서
Worktree  = 복사본 (여기서 고쳐도 원본은 그대로)
merge     = 복사본의 수정사항을 원본에 합치기

실제로 해보기

프론트엔드와 백엔드를 동시에 개발하는 흐름이에요.

1) 작업 분리 계획
   프론트엔드 + 백엔드를 동시에 진행하자!

2) 워크트리 만들기
   git worktree add ../frontend
   git worktree add ../backend

3) 각 터미널에서 클로드 코드 따로 실행
   터미널 1:  cd ../frontend && claude
             "프론트엔드 UI 컴포넌트를 만들어줘"
   터미널 2:  cd ../backend && claude
             "백엔드 API 엔드포인트를 만들어줘"

4) 끝나면 합치기
   git merge frontend-branch
   git merge backend-branch

5) 정리 (중요!)
   git worktree remove ../frontend
   git worktree remove ../backend
   # 폴더를 직접 지웠다면:
   git worktree prune

명령어 한눈에

잘못된 예 vs 올바른 예

• 잘못된 예: 작업 끝나고 폴더만 휙 지움. → Git 에 워크트리 정보가 남아 꼬여요. (이럴 땐 git worktree prune 으로 정리)
• 올바른 예: git worktree remove 로 깔끔히 정리. → 남는 찌꺼기 없이 끝나요.

또 다른 사례를 볼게요.

• 잘못된 예: 프론트와 백 팀원이 같은 파일을 동시에 고침. → 합칠 때 머지 컨플릭트(같은 줄을 둘 다 고쳐 Git 이 못 합치는 상황) 발생.
• 올바른 예: "이 파일은 프론트, 저 파일은 백"으로 미리 나눔. → 합칠 때 충돌이 거의 안 나요.

이럴 때 이렇게: 동시 작업 전에 "누가 어느 파일을 만질지"부터 정하세요.

한 걸음 더 ▸ 흔한 실수 정리

• 같은 파일을 두 에이전트가 동시 수정 → 충돌.
• worktree 쓰고 remove 안 함 → 워크트리 정보 꼬임.
• 에이전트끼리 MCP 로 소통 시키려 함 → 그럴 바엔 서브에이전트가 더 효율적.

올바른 마음가짐은 이거예요. 에이전트 하나하나를 "주니어 개발자 한 명"이라고 생각하고, 작업 환경(프론트/백, 레이어별)을 충분히 떼어놓는 거예요.

기억할 점

• 독립 에이전트는 여러 터미널에서 클로드 코드를 따로 동시에 켜는 방식이에요.
• Git Worktree 로 같은 프로젝트의 폴더를 나눠 충돌을 막아요.
• 한 프로젝트의 여러 기능을 동시에 개발할 때 좋아요.
• 끝나면 반드시 git worktree remove 로 정리해요.
• 각 에이전트를 주니어 개발자라고 생각하고 일을 나누는 게 핵심이에요.

한눈에 비교표

병렬 실행 vs 직렬 실행

서브에이전트 vs 독립 에이전트

기본 서브에이전트 vs 커스텀 서브에이전트

연습문제

문제 1: 병렬일까 직렬일까 (기본)

다음 셋을 병렬과 직렬 중 어느 쪽이 맞는지 고르고 이유를 말해보세요. - (A) 웹사이트를 영어, 일본어, 중국어로 동시에 번역 - (B) DB 스키마를 만들고, 그 스키마에 맞는 API 를 개발 - (C) 서로 독립된 유닛 테스트 파일 10개를 동시에 실행

문제 2: 코드 리뷰 전문가 만들기 (중급)

코드 리뷰 전용 커스텀 서브에이전트를 설계해보세요. 프론트매터(name, description, color)와 역할 핵심을 적어보세요.

---
name: code-reviewer
description: Use this agent when you need to review code changes
  for best practices, security issues, and performance problems.
color: blue
---

You are a Code Review Specialist.

1. 코드 품질 분석
   - 변수명/함수명이 의미를 잘 전달하는지
   - 불필요한 중복 코드 찾기
2. 보안 취약점 검토
   - SQL 인젝션, 하드코딩된 키 감지
3. 성능 문제 점검
   - 느린 쿼리, 불필요한 연산
4. 절대 하지 말 것
   - 코드를 직접 수정하지 말 것 (리뷰만!)
   - 결과는 마크다운 리포트로만 출력

문제 3: Git Worktree 실무 (심화)

쇼핑몰에서 프론트엔드(상품 목록 UI)와 백엔드(주문 API)를 동시에 개발하려 해요. Git Worktree 로 두 에이전트를 병렬 실행하는 전체 과정을 정리 과정까지 포함해 적어보세요.

# 1) 메인 브랜치에서 시작
git checkout main

# 2) 프론트엔드 워크트리 (새 브랜치)
git worktree add ../shop-frontend -b feature/product-list-ui

# 3) 백엔드 워크트리 (새 브랜치)
git worktree add ../shop-backend -b feature/order-api

# 4) 터미널 1 — 프론트엔드
cd ../shop-frontend
claude
# "상품 목록 UI 컴포넌트를 만들어줘"

# 5) 터미널 2 — 백엔드
cd ../shop-backend
claude
# "주문 REST API 엔드포인트를 만들어줘"

# 6) 둘 다 끝나면 메인에서 합치기
git checkout main
git merge feature/product-list-ui
git merge feature/order-api

# 7) 정리 (반드시!)
git worktree remove ../shop-frontend
git worktree remove ../shop-backend

용어 사전

참고 자료

• 클로드 코드 공식 문서: 서브에이전트 생성·관리 가이드, 그리고 최신 요금·모델명·콘텍스트 한도는 이곳에서 확인.
• Git Worktree 공식 문서: git-scm.com/docs/git-worktree — 명령어 레퍼런스.
• 코드팩토리 GitHub: github.com/codefactory-co — 저자의 예제 저장소.

다음 장에서는 또 다른 활용법을 이어서 다뤄요. 지금 당장 몰라도 됩니다.